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Feedback 


Please send all feedback to assembly@qdosmsq.dunbar-it.co.uk. You may also send articles 
to this address, however, please note that anything sent to this email address may be used in a future 
issue of the eMagazine. Please mark your email clearly if you do not wish this to happen. 


This eMagazine is created in 4I¢Xsource format, aka plain text with a few formatting commands 
thrown in for good measure, so I can cope with almost any format you might want to send me. As 
long as I can get plain text out of it, I can convert it to a suitable source format with reasonable ease. 


I use a Linux system to generate this eMagazine so I can read most, if not all, Word or MS Office 
documents, Quill, Plain text, email etc formats. Text87 might be a problem though! 


Subscribing to The Mailing List 


This eMagazine is available by subscribing to the mailing list. You do this by sending your 
favourite browser to http: //qdosmsq.dunbar-it.co.uk/mailinglist and clicking on the 
link “Subscribe to our Newsletters”. 


On the next screen, you are invited to enter your email address twice, and your name. If you wish 
to receive emails from the mailing list in HTML format then tick the box that offers you that option. 
Click the Subscribe button. 


An email will be sent to you with a link that you must click on to confirm your subscription. Once 
done, that is all you need to do. The rest is up to me! 


1.3 


2 Chapter 1. Preface 


Contacting The Mailing List 


I’m rather hoping that this mailing list will not be a one-way affair, like QL Today appeared to be. 
I’m very open to suggestions, opinions, articles etc from my readers, otherwise how do I know 
what I’m doing is right or wrong? 


I suspect George will continue to keep me correct on matters where I get stuff completely wrong, as 
before, and I know George did ask if the list would be contactable, so I’ve set up an email address 
for the list, so that you can make comments etc as you wish. The email address is: 


assembly@qdosmsq.dunbar-it.co.uk 


Any emails sent there will eventually find me. Please note, anything sent to that email address will 
be considered for publication, so I would appreciate your name at the very least if you intend to 
send something. If you do not wish your email to be considered for publication, please mark it 
clearly as such, thanks. I look forward to hearing from you all, from time to time. 


If you do have an article to contribute, I'll happily accept it in almost any format - email, text, Word, 
Libre/Open Office odt, Quill, PC Quill, etc etc. Ideally, a IATRXsource document is the best format, 
because I can simply include those directly, but I doubt I'll be getting many of those! But not to 
worry, if you have something, I'll hopefully manage to include it. 


It’s probably a little late to wish you a Happy Christmas but this year all my followers received a 
free download of a slightly updated eBook containing all the articles published in QL Today over 
the past ‘n’ years (longer than I care to think about!) 


All the diagrams etc have been converted from ASCIU art to use proper png formats created with 
the “graphviz” utility (http://www. graphviz.org/). There was quite a bit of work involved in 
getting the old text, diagrams and code converted to IATEX(that’s how they like it to be written!) but 
I think, so far, everyone thinks that a good job has been done. Even if I say so myself. 


The eBook has been typeset using I4IRXwhich is a professional system, much loved and used 
in academia and science for thesis! and scientific papers. I even have a couple, probably more, 
technical manuals written and published using I4TRX, my favourite being Compiler Design in C by 
Allen Holub. Speaking of compiler design, there are some relevant bits coming up in this issue on 
this matter, but don’t panic! 


If you have not already downloaded your free copy - it’s in pdf format only at the moment, 
then please go to http: //qdosmsq.dunbar-it.co.uk/downloads/QLToday/QL_Assembly. 
pdf and help yourself. I am looking into converting the pdf to other formats as some of my 
readers would like a version for Kindle and other eReaders. 


Elsewhere in this issue, you will find some observations by George Gwilt on this eBook and its 
contents. George also has comments and observations on the first issue of this eMagazine, they are 
coming up next... 


Happy new year, may all my readers enjoy a prosperous 2015. 


'What is the plural of thesis? 


This chapter is dedicated to George Gwilt’s feedback on some of the content of the first issue of the 
eMagazine. 


Special Programs 


As Norman says, Special Programs are signalled by an extra word, $4AFB, after the program’s 
name. In such a program there follows a set of instructions ending with RTS. These instructions are 
called as a subroutine inside the keywords EX, EW and ET (EX..) before they get around to creating 
and activating the job. That is why the instructions are obeyed “in the context of SuperBASIC’, as 
are all keywords. 


[ND] Now that small explanation makes it all clear, which is more than the official docs have been 
able to do! (For me, anyway.) 


A description of how to write such a subroutine is given in section 3.5 of Jochen Merz’s QDOS 
Reference Manual. 


An example of the use of a special program is to be found in the SMSQ/E source code, in the 
program extras_exe_source_cct_asm. This program aims to concatenate a set of files and write 
them to an output file. All these files, including the output one, are to be named as channels to 
the program when it is executed. EX.. would happily try to open these, putting their [Ds on the 
stack. If the output file does not exist, an error would be signalled by EX... It is to avoid this that 
the special program is invoked. 


Having dealt with pipes and the parameter string, EX.. will go through the list of channels appearing, 
separated by commas, after the program name. But, just before this is done the special routine is 
called. This allows the program ..._cct_asm to process the channels itself. It is thus able to open 
the output file as a new one, as well as processing the set of files to be concatenated. When it has 
finished doing this it amends the pointers to the parameters, set in A3 and AS, so that EX.. find that 
there are no channels to deal with before activating the job. 


3.2 


3.3 


3.4 
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The Extra 12 bytes 


The program in SMSQ/E which contains the code for EX.. is sbsext_ext_exsbas_asm which 
also contains the code for Special Programs. The program calculates how much data space to set 
for the Trap #1 call to MT_CJOB, which creates the job. If r is the number of channels and p the 
length of the parameter list, the addition made to the program’s data space is: 


4(r+3)+p 


rounded up to even. 


The reasoning is this. For each channel we need 4 bytes; for the parameter string we need p bytes, 
rounded up; for the two counts we need 4 bytes; and, just in case there are two pipes, we need a 
further 8 bytes. If both r and p are zero you can see that indeed 12 bytes are added. Also, if there 
are no pipes then 8 bytes have been added unnecessarily. 


The EX Files - Page 6 


When a job is activated the registers A4 to A7 are set as Norman describes apart from two details. 


e The size of data space is A5 — A4 not AS. 

e A6 certainly points to the end of the internal job header, but not necessarily to the start of 
code. This is because, when a job is created by MT_CJOB, A1 either points to the absolute 
address of the start of code or is zero. Only when A1 is zero does A6 point to the start of 
code, which in this case does follow the internal header. 


[ND] Ugh! A silly mistake to make in the case of A5. I had also forgotten that a job can be created 
with the code immediately following the job header or with just a pointer to existing code elsewhere 
in memory. 


The facility to choose the address of the start of code allows the setting up of several programs, 
which have to be re-entrant, each with the same copy of code in ram, but, of course, with different 
data spaces and internal job headers 


[ND] A perfect example of this is Adrian Dickens’ Self-cloning Program in chapter 4.4.2 of The QL 
Advanced User Guide, page 55. Unfortunately, as written, it uses an absolute address to fetch the 
SV_RAND word from the system variables, so probably will not work on many modern machines. 


LibGen Lite Errors 


The program as it stands will not run on an unexpanded QL, though it should work on QPC2, 
for example. The reason is that ’buffer’ is set up at an odd boundary. Oddly enough this is quite 
obvious from the example of the use of the program. This contains the line: 


BUFFER EQU *+$000000017 


This is an error I found myself committing again and again. It is caused by having an odd number 
of characters in the preceding string. Now, I always set strings using code which ends with: 


DS .W 0 


3.5 


3.6 


3.5 ET Phone Home 17 


This sets the PC to the next even boundary from the end of the string. QPC2 has the 680020+ 
instruction set which allows word and long word accesses to an odd boundary which the 68000/8 
does not. 


[ND] Another silly mistake. I could have sworn I used DS.W to ensure that storage was reserved 
and was on a word boundary, it turns out I used DS.B which gives rise to the problem George has 
pointed out above. 


ET Phone Home 


I have never been able to use JMON. On the other hand I use QMON regularly. Indeed I did use it 
to go through the (working) version of LibGen_Lite I typed up. However, to call QMON I had to 
put a commma between QMON#6 and 23. 


I should explain that I always use QMON in a daughter basic set up with #6 opened to a CON 
channel with window 512,204,0,0 and name ’x’, for easy access. Also I had more programs running 
than Norman when I ET’d LibGen_Lite. 


I’m afraid I used NET_PEEK to find LibGen_Lite’s program number after ETing it. I also 
sometimes used NET_PEEK instead of QMON to see what was on the stack after ETing. 


Actual Use of LibGen_Lite 


Norman’s program helps to solve a real problem. This is when you want to include an assembled 
program using the command LIB, which brings in the binary. 


This has no symbols, so, if you want to access the program at some intermediate points you need to 
set up an appropriate set of equates. 


This of course is what LibGen_Lite does. It will arrange for an appropriate SYM_LST file to be 
added just before the LIB which brings in the program itself. 


A real example is the program PEAS_BIN, which is part of EasyPEasy. This program, will, on 
assembly, give rise to a SYM_LST file with over 50 entries. In fact only six of these are required to 
access the set of subroutines. 


It would not matter too much if all the entries were included in the SYM_LST file, were it not that 
many of the unwanted equates referred to nondescript labels such as "11" and "12" which could well 
be used in the main program thus causing an error in assembly. 


In fact I did find just that which made it impossible to use the complete SYM_LST file. Hence the 
abbreviated SYM_LST file published with PEAS_BIN. 


So, the question is, how might one amend LibGen_Lite to produce a required subset of equates? 


[ND] One suggestion that comes rather quickly to mind, is to have a well documented format for 
the _SYM file which would allow the program to simply scan through looking for the “record type” 
that determines when a symbol is an offset to some code, or a simple EQU. 


I did originally write a small SuperBasic routine to extract the code offsets symbols and their values 
from a raw _SYM file, but was advised by George that the _SYM files created by GWASL and 
GWASS are different and that it would be best to use the textual SYM_LST files instead. 


Another method would be for me to iron the bugs out of the full sized LibGen and get it working! 


George has some comments elsewhere in this issue on the Christmas eBook in which he mentions 
my lack of useful uses of the LINK, UNLK and PEA instructions. 


I mentioned compilers earlier myself, so now is the time to combine these into an example of the 
use of these instructions, which were, apparently, originally designed for compiler writers to use. 
They are certainly useful for converting C code, for example, into assembler. Take the following 
slightly contrived C code: 


void addTwoNumbers(short value_a, short value_b, long *result) 


{ 


long temp; 


temp = value_a; 
temp += value_b; 


*xresult = temp; 


} 


int main(int arge, char xargv[]) 


{ 
long Answer = 0; 
shiont  ae= 274 
short b = 33; 
addTwoNumbers(a, b, &Answer) ; 
printf ("a=%d, b=%d, at+b=%ld", a, b, Answer); 


Listing 4.1: Contrived C Code 


You can see that addTwoNumbers is a rather simple function that takes two values to be added 
together, value_a and value_b, which are short integers, or 16 bit words in assembly speak, and a 
pointer to a long integer, result. Result is the address of a 32 bit long word, where the calculated 
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value will be stored. 


The two numbers to be added are passed by value, while the result variable is passed by reference. 
This means that regardless of what the function does to the variables value_a and value_b, nothing 
will happen to them in the calling program as within the function, they are copies of the variables 
rather than the actual variables themselves. 


In C, if you wish to amend a variable passed as a parameter to a function, then you must pass the 
address of the variable - a reference to the variable in other words. Mind you, the reference is itself 
passed by value as a copy of the real address, so the function cannot change the address, only what 
it points to. 


Did I mention how simple compiler writing is? (George might have some comments to make 
here, he is Turbo Man these days and maintains and improves the much loved Turbo Compiler and 
toolkit.) 


Yes, I know the C code above can be rewritten to be much much simpler, and to return the actual 
result through the normal manner in C, using the return command, but bear with me, I’m trying 
to demonstrate the LINK, UNLK and PEA instructions! 


The local variable temp will have space allocated on the stack for it, and when the function ends, 
this temporary work space will be removed. With a compiler producing code for the Motorola 
68000 series of processors, the code generated could resemble the following. 


main equ *x 

Answer dc.1 O 

a dc.w 27 

b dc.w 33 
lea a,a0 Get address of a. 
move.w (a0),—(a7) Stack a’s value 27. 
lea b,a0 Get address of b. 
move.w (a0),—(a7) Stack b’s value 33. 
pea Answer Stack reference to Answer. 
bsr addTwoNumbers 

Stack_tidy adda.1l #2+2+4,a7 Tidy the stack. 


Listing 4.2: Contrived Assembly Code 


The code for main starts with some space allocated for the variables defined within the C code. 
Then, a copy of the values of variables a and b are pushed onto the stack, followed by the address 
of the variable Answer. 


After the function call, these 8 bytes are tidied off the stack, before main carries on with whatever 
comes next. 


The PEA instruction is roughly equivalent to the following code: 


lea Answer ,a0 
move.1 a0Q,—(a7) 


Listing 4.3: PEA Equivalent Code 


Back to the contrived example, the assembly code created for the function, might be as follows: 


16} addTwoNumbers equ * 


Ly 
18 
19 
20 
21 
22 
23 
24 
25 
26 


21 


link a6,—4 Local variable temp. 
move.1 a0,—(a7) Save working register. 
clr.1 —4(a6) Locals default to zero. 


move.w $0e(a6),—4(a6) Get value_a. 
add.w $0c(a6),—4(a6) Add value_b. 


move.1 $08(a6),a0 Fetch address of Answer. 
move.1 —4(a6) ,(a0) Copy temp into Answer. 
move.! (a7)+,a0 Restore working register. 
unlk a6 Clean up temp, a6 and a7. 
rts 


Listing 4.4: Contrived Assembly Code - AddTwoNumbers 


This code starts by creating space, 4 bytes, for the local variable named temp using the LINK 
instruction which creates a stack frame big enough to hold all the local variables required, and sets 
A6 to be the frame pointer. It does this effectively as per the following code: 


move.1 a6,—(a7) Save current a6. 
movea.|1 a7,a6 A6 is the frame pointer. 
adda.l1 #—4,a7 Create space for locals. 


Listing 4.5: LINK Effective Code 


With a6 as the frame pointer, the code can access local variables using a negative offset from A6, 
and access the function parameters with a positive offset from A6. Any working registers pushed 
onto the stack will go below the space required for the local variables used in the function. At this 
point, the stack looks like Figure 4.1 


— | Space reserved for temp. 


Frame Pointer in A6.L - 
Stack pointer in A7.L + . 


Figure 4.1: The stack structure 


After setting the temp local variable to zero, the calculation is done and the result stored in the long 
word pointed to by result which is the address of the variable Answer, and the stack is tidied by 
popping AO and then by unwinding the stack frame previously allocated using the UNLK instruction, 
which effectively, does this: 

move.!1 a6,a7 Set a7 back again. 

move.1 (a7)+,a6 Retrieve previous a6. 


Listing 4.6: UNLK Effective Code 


And now, A7 points once again, at the return address in main, where execution will continue. The 
local variable temp is no more, it has ceased to be, it has shuffled off its mortal coil and gone to 
meet its maker, etc. ! 


'Monty Python’s Dead Parrot sketch. 


And it’s good news, of a sort! 


As my wife was away for the weekend recently, I took the opportunity to spend some time going 
through the problems I have been having with LibGen. 


If you remember, I had managed to reach a stage where the program would assemble and execute, 
but on exiting, QPC would be trashed in as much as the cursor passed behind the window for QPC 
and therefore I was unable to get any further work done within QPC and I had to kill it. 


This problem could be reproduced at will, and was apparent even if all I did was ex LibGen_exe 
and then, when it was running, pressed ESC to escape. QPC was hosed at this point. 


It turned out that some modifications I had made to the window definition, in order to allow me the 
ability to create a new application sub-window menu dynamically, had caused the problem. One 
problem that I did notice was that I had set the pointer to the menu items status bytes to be zero, 
which meant that it used the status bytes for the main window’s loose items instead. 


There were probably other errors as well, but in the end, I recreated the Window using SETW as 
per the original article in QL Today, and everything is fine again. 


So, the good news is, I’ve got a working starting point for the rest of the development. The bad 
news? Time is never on my side! 


A thread on the QL Forum, entitled Command Line Parameters mentioned at one point, the ability 
to get a parameter as a name rather than a string. Now in all my years of Assembly programming, 
writing DJToolkit etc, I’ve never really bothered with names. The following listing is a small 
example of how to copy a single name parameter as passed to a procedure or function written in 
Assembly. 


It does not do anything useful, other than take the name passed, run some checks on it, then if valid, 
copies it to a buffer and prints it to SuperBasic channel #1 which is assumed to be open. 


The Code 


; A test routine to fetch a name from the supplied parameters to 
; a PROCedure in this case, which keeps things simple. The name 
TO CUeSt LON Iss copied stoma buiiien | then printed stom echiannela il, 
s  Atingw as eillil 


; GetName #1, something not_in_quotes 


getName seme dia xt 


start lea define ,al Procedure definition block. 
move .w bp_init ,a2 Initialise Procs/FNs. 
jmp (a2) Do it, exit to SuperBasic. 


define dc.w 1 One Procedure. 


Nw bv wv 
AYAN 


45 
46 
47 
48 
49 
50 
51 
22 
a 
54 
55 
56 
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dc.w getName—« Starting address offset. 

dc.b 7,°> GetName’ Name of procedure. 

dc.w 0) End of Procedures. 

dc.w 0 There are zero Functions. 

dc.w 0 The end of those too. 
buffer ds .w 14512 Word count and 1024 bytes. 


Listing 6.1: GetName - Definition Block 


We start the code with the standard new procedure and/or function definition block. Following this 
is a buffer of 1024 bytes and an extra word for the usual QDOSMSQ string length. You will notice 
I’ve used ds.w instead of ds.b to ensure that the buffer starts on a word boundary. 


; A name table entry is 8 bytes, as follows: 


© Gisictu oo 1Ze me Diesicniptiion 

: 0 word Type 

: D, word Index of name in name list , or —l (expression.) 
: 4 long Offset into variables area for value of this 

3 name, or SuperBasic line number, (SB Functions & 
H Procs) or Absolute address in memory (for MC 

; Functions/Procs ). 


Aa mame Inst memtnyeulsee:ni ss ibiyites!eusas sioililiowsi: 


; Size Description 
; byte Length of this name. NOT word aligned. 
; bytes Bytes of name. 


Listing 6.2: GetName - Name Table & Name List Definition 


The comment above simply reminds us (me!) of what a name table entry looks like. Each entry is 8 
bytes and on entry to a procedure or function, A3 and A5 point, relative to A6, at the first and last 
of the supplied parameters. 


In the parameter list, the byte at offset 1 holds details of the separators used in the parameter list. 
This is not used in the main name table though. 


>) Aomame list entry os) ni bytes!) vas: woilliliows: 


; Size Description 
; byte Length of this name. NOT word aligned. 
; bytes Bytes of name. 


err_bp equ =15) Bad parameter error code. 
bv_ntbas equ $18 Offset to Name Table. 
bv_nlbas equ $20 Offset to Name List. 
bv_chbas equ $30 Offset to channel table. 


Listing 6.3: GetName - Equates 


62 
63 
64 
65 


66 
67 
68 
69 
70 
eat 
72 
a3 
74 
75 
76 
a 
78 
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Another comment reminds us of how each entry in the name list looks, and is followed by a few 
equates that will be used later. 


Now we get to the meat of the code. 


getName tst.b 0(a3 ,a6.1) Is the type a NULL? 
beq.s nameFound No, bale out, not a name. 
bp_error moveq #err_bp ,d0 Bad parameter 
rts We are out of here! 


Listing 6.4: GetName - Checking Parameters 


We begin by testing to see if the type byte of the first parameter passed is unset, which indicates a 
name. If it isn’t a name, we bale out to SuperBasic with a bad parameter error. 


nameFound movea. 1 bv_ntbas(a6),a0 Name Table start in AO. 
move .w 2(a3 ,a6.1),d0 Name list index number. 
Isl .w #3 ,d0 Multiply by 8. 
adda.w d0,a0 AO = Name Table entry. 


Listing 6.5: GetName - We Have a Name 


Here we know we have a name, so we begin by getting the offset of the start of the name table into 
AO. From the passed parameter details, we extract the index number of this parameter’s entry in the 
real name table (the parameter entries are copies and as each entry is 8 bytes, a quick shift three 
bits left will do the multiplication for us. 


Adding D0 to AO gets us the offset from A6 where we can find this name in the name table. 


; Now, from AO’s position in the Name Table, access the Name 
2 ILS, mellaiwve te AO OF C@UrSE . 


move .w 2(a0 ,a6.1),d0 Offset into the Name List. 
ext. 1 do Make it long. 
add.1 bv_nlbas(a6),d0 DO = Name List offset. 


= We now have the stext of thie name. inthe name list. at. thic 
SO dsict ain DOr 


Listing 6.6: GetName - Find it in the Name List 


In the name table, we pick up the offset into the name list for this name. The name list holds the 
actual characters of the name. As ever, everything is relative to A6. 


lea buffer ,a3 Destination buffer. 
moveq #0,d1 Clear length WORD. 
move.b 0(a6 ,d0.1),d1 Get length BYTE. 
clr.b 0(a3 ) Buffer size word top byte 
: must be Zero. 
copy_name move.b 0(a6,d0.1),1(a3) Copy one byte into buffer. 
addq. 1 #1,a3 Next free space in buffer. 
addq.1 #1,d0 Next char in Name List. 


dbra dl , copy_name Copy size byte plus name 


89 
90 


101 
102 
103 
104 
105 
106 
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| ; bytes. 


move.b #linefeed ,1(a3) And tag on a linefeed. 
Listing 6.7: GetName - Copy Name to Buffer 


A3 is set to the address of the destination buffer for the characters in this name and d1.w is cleared 


as we need a word sized counter. As the name list entry is byte sized, we get the length into D1’s 
lower byte. 


Normally, we would decrement D1.w before we start copying bytes, but in this case, we are copying 
the size byte from the name list, so we keep hold of the extra one byte in the counter to account for 
that. 


The first byte in the buffer is cleared as the length word’s high byte can never be anything but zero 
when copying from the name list. 


The loop at copy_name copies first the size byte and then all the characters of the name into the 
buffer one by one. When we are done copying, the linefeed character is stored at the end of the 
name’s bytes. 


You will note, at this point, that the length word at the start of the buffer has no idea that the linefeed 
has been added. We are keeping it in the dark for now. 


Looking at the above code, I should really have got rid of all those 1(An) offset instructions and 
started with a post increment of A3 or similar, but hey, the code works! I'll probably get a telling 
off from George though! ;-) 


* Now we have the text of the name im our buffer. Find channel 
2 #1 in the ‘channel tablle. We shouldnt be off the end) of the 
; table , so NOT CHECKED. 

; We assume #1 is open too, so that’s NOT CHECKED for either. 


findChan moveq #40 ,d1 Offset to entry #1. 
move. | bv_chbas (a6) ,a0 Channel table base offset. 
adda. 1 dil ,a0 Required entry for #1. 
move. | 0(a6,a0.1),a0 AO is ID of channel #1. 


Listing 6.8: GetName - Checking Channel #1 


The code above deep dives into the SuperBasic channel table. It takes no account of where the end 
of the table might be, nor even if channel #1 is closed or not. It assumes much. Production code 
would never do such a thing! 


Each entry is 40 bytes long, and the channels number from zero, so we need the second entry in the 
table. 


AO is set to the start of the channel table, D1 holds the offset to #1, and is added to AO. The first 
long word in each entry is the channel id as far as QDOSMSQ is concerned. What SuperBasic 
knows as #1 could be anything, but back in the old days, was something like $00010001. But never 
assume this to be the case now. 


JP pimtethemtexctmwe sceadmiromemthicn mantel ist tomchtammielert ln 

printName move.w UT_MTEXT, a2 Vector to print a string. 
lea buffer ,al The string to print. 
addi.w #1,(al) Include the linefeed 
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107 jmp (a2) Print it, and exit 
108 § ; to SuperBasic. 


Listing 6.9: GetName - Printing the Name 


And finally, with AO holding the QDOSMSQ channel id, we point A1 at the buffer start and add 
1 to the word stored there to account for that linefeed we sneaked in earlier. With the buffer now 
ready to print, we jump into QDOSMSQ to print the text to #1 on the screen and never return. If 
there are any errors in the printing of the name, SuperBasic will handle it. 


6.2 Howto Run the Code 


Type the above into your favourite editor and assemble it. Then simply LRESPR the assembled file 
and the new routine named GetName is available for use and abuse. To run it, type the following: 


GetName This_has_no_quotes 


This example will simply print what you passed, on screen, wherever channel #1 happens to be. 
Remember to run this in a SuperBasic or Sbasic that has at least channel #1 open. Other examples 
could be file names: 


GetName flp1l_boot 
GetName winl_source_qltoday_LibGen 


And if you try passing a number or a string, then you should get a Bad Parameter error message. 


6.3 What if There Are More Parameters? 


The code example assumes only one parameter will be passed, but makes no checks. In real code, 
you might be expecting a number of parameters so you would check the numbers passed and their 
types before fetching them one by one (for the names) and then getting the others in groups as per 
normal. 


You don’t need to clean the values for names off the stack as they are never on it. You will, for the 
strings, integers etc. Not so much in procedures, but most definitely in functions. 


by 


ey 


Eommaents by Ceaige Gwilt 
mm = . ~_ADp 


The following is a list of observations and comments from George, on the first version of the 
QL_Assembly.pdf eBook, which was made available for download just before Christmas. Since 
then, it has been updated to include the following. 


Here are some notes on your Assembly Language Programming Series. 


1. The definition of LEA on page 37 should state that the effective address put into the address 
register is a long word. The official definition by Motorola states that the size is long. 
[ND] Fixed. 
2. The PEA instruction is defined on page 39. As for LEA the size for PEA is long. This should 
be made clear. 
[ND] Fixed. 
3. On page 39 you ask what use PEA is, when LEA could be used instead. There are three 
answers. 
(a) Using LEA requires the use of a register, such as Al, whereas PEA does not. It also 
needs one more instruction. 
(b) PEA allows you to choose between several subroutines but return to the same address 
form each. An example occurs in GWASS: 


PEA INS_FP4 the return address 
BEQ FP_XD 
BRA FP_XS 


Listing 7.1: PEA Example from Gwass Assembler 


(c) PEA can be used to put a number on the stack. EG 


PEA 4 puts 4 on the stack. 
Listing 7.2: PEA Stacking a Literal Value 


[ND] I did cover these in the book, at least the part about needing two instructions, and a 
register. 
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4. 


5. 


7. 


8. 


| 


1 
2 


a: 


On page 40 the first line is wrong (as you can easily see!). 

[ND] Yes indeed I can! Oops. 

On the same page you deal with LINK, suggesting that it is probably most used by compilers. 
The official Motorola User’s Manual says that LINK and UNLK can be used to maintain a 
linked list of local variables and parameter areas on the stack for nested subroutine calls. 
As it happens I use LINK/UNLK in GWASS as part of the assembly of macros. Each area 
allocated by LINK is used to store the macro parameters. Since the number of these can vary 
from macro to macro, I need to use LINK with a variety of displacement values. 

Moreover, since macros can contain calls to other macros, the set of LINK/UNLK instructions 
can indeed be nested. 

In order to allow a variety of displacements I produce a table of pointers to the different LINK 
instructions needed. This, of course, is done by means of a macro. 

One problem with the use of nested LINKs is that each time you use a further one the available 
stack space becomes smaller. To avoid trouble I check for each new LINK that there will 
indeed be enough space for it. 

[ND] See elsewhere in this issue for a few examples of PEA, LINK and UNLK. 


. Section 6.4 deals with exceptions. The descriptions of the stack frame at the bottom of page 


48 and the top of page 49 are upside down. I think this is copied (wrongly) from Pennel’s 
QDOS Companion page 91. Also, the description on page 49 is an atypical exception stack 
frame and applies only to the 68000/8 Bus or Address Error. 

[ND] It was actually copied from the official Motorola 68000 Programmer’s Reference 
Manual, 4th Edition page 39. On that page there is a diagram of the MC68000 and MC68008 
Group I and Group 2 Exception Stack Frame which shows the SSP pointing at the Status 
Register at the low address of the stack frame, then the PC high word and PC low word are 
next, going up in memory. 

I wonder if the Motorola book is wrong? 

The final line on page 48 explains that the diagram on page 49 is indeed for a BUS ERROR, 
ADDRESS EROR or a RESET exception and that those three differ from all the others. ] 
Section 6.5 deals with a redirection of some of the traps and exception vectors. These range 
from address error to trap #15. You then show how to program each exception handler. I 
would very much suggest that this is definitely something to avoid. The main reason for 
MT.TRAPV probably is to allow the user to alter only one or two of the handlers, in particular 
the traps numbered 5 to 15, which are not used by QDOS. 

[ND] Fair point. The example did show redefining all the available vectors, which could be 
handy, in a debugger/monitor perhaps. I agree that redefining one or two might be more 
common. 

A minor point in 7.2 on page 54 is that I would use 


jmp (a2) 
Listing 7.3: Saving an RTS Instruction 


instead of 
jsr(a2) 
rts 


Listing 7.4: Wasting an RTS Instruction 


[ND] Yes, I have a habit of doing that. 

You can operate doubly linked lists, described on page 118 by using only one pointer instead 
of two. Replace the two addresses, next (A say) and prior (B say) by their XOR combination 
(C say). 
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Thus 

C=AxorB 
so that 

B=AxorC 
and 

A= BxorC 


[ND] This is quite neat, and I have seen it used before, a long time back. I suspect back then 
there was a need to save every possibly byte at the expense of having to use a couple more 
instructions to extract the data required - but I am rather fond of the XOR operation, I have 
to Say. 
To illustrate how such a doubly linked list can be operated I have produced a small PE 
program. This has loose items A, D, H and W. 

e A adds an item (to the start of the list). 

e D deletes an item from the list. 

e H prints the number of items in the list. 

e W prints, in hex, the address of an item. 
Since this program is designed to show how to perform these operations not as a real working 
program with a real list, the list is constrained to consist of items which are simply a digit 
between 0 and 9 inclusive. 
The minimum initial information you need is the address of the first item, stored at fadd(A6), 
and the address of the last item, stored at ladd(A6). 
These are made zero when the program starts so that initially there is no list. 
The program is given below. 


Sesh amasm 
bra.s start 
dc. 1 0 
dc.w $4afb 
fname dc.w fname_e—fname —2 
dc.b "LIST v1.01" 
fname_e ds.b 0 
ds .w 0 
in winl_ass_pe_keys_pe 
in winl_ass_pe_qdos_pt 
in winl_ass_pe_keys_wwork 
in winl_ass_pe_keys_wstatus 
in winl_ass_pe_keys_wman 
in winl_ass_pe_keys_wdef 
in winl_lib_hedl 
rsset 0 
id rs. 1 1 
wmvec rs.1 1 
slimit rs.1 1 
fadd rs. 1 1 
ladd rs. 1 1 
num rs. 1 1 long int for conversion 
buf rs. 1 2 ASCII hex of num 
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start 


; We need 
; and the 


stl 


wrpt 


con 


ope 


lea (a6,a4.1),a6 dataspace 

clr 1 fadd(a6) mark 

@\lir ll ladd (a6) no list 

bsr.s ope open a con channel 

move. | a0 ,id(a6) keep the ID 

moveq #iop_pinf ,d0 

moveq #—1,d3 

trap #3 

tst.1 do ptr_gen present? 

bne sui —— .. no 

move. | al , wmvec(a6) keep WM vector 

beq sui ———> wasn’t there! 

movea. 1 al ,a2 set WM vector in A2 

lea slimit(a6),al 

moveq #0 ,d2 this must be zero 

moveq #iop_flim ,d0 max size of window 

trap #3 

subi. 1 #$C0008 ,( al) less 12, 8 

lea wd0, a3 window definition addr 

move. l #ww0_0,dl size of working definition 

bsr getsp sets ALCHP’d addr 

movea. 1 a0 ,a4 to AO and to A4 

TOmsient status area to zeros 

loose items to "available" (zero) 

lea wst0 ,al Status 

movea. 1 al ,a0 area 

moveq #wst0O_e—wst0 —1,d1 bytes to clear — 1 

clr .b (a0)+ 

dbf d1,stl 

movea. 1] id(a6),a0 Replace the channel ID 

move. l wd_xmin+wd_rbase(a3),dl minimum size 

andi. 1 #$FFFOFFF , dl Lop off scaling factors 

jsr wm_setup(a2) Set up working defn 

moveq #—1,d1 Set the window 

jst wm_prpos (a2) where the pointer is 

jst wm_wdraw (a2) Draw the contents 

jst wm_rptr(a2) Read the pointer 

beq.s no_err Since DO is zero then 
D4 is non zero 

bra sul —_-—> DO is non zero 

dc.w 3 

dc.b >con’ 

lea con , a0 To open "con" ; 

moveq #—1,d1 for this job 

moveq #0 ,d3 

moveq #i10_open , d0 

trap #2 

rts 
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= \We come  hene siti we 
; This means that D4 
; there was a window 
; action routine has 
; window event (and 

2 \lneen SCE im Unie 


lit cay loose item shia 
Stine went wall moi 
7 litem “s) action Tout 
7 items action= nowt 
J viectonsand force a 
; number in D4. In t 
7 Onwthne sot hetmamnand 
A PROCES sm Uhie wevienit 


no_err movea. 1 
btst 
bne 


btst 
beq.s 
bsr 
bra.s 


; Loose item action 
; MOVE 


afun0_0O bsr 

afl move .w 
move.b 
moveq 
Aisi 
clr.b 
moveq 
moveq 
EES 


5 SIT 


afun0_3 moveq 
moveq 
bset 
rts 


; A — Add an item to 


afun0O_1 move.1 
bsr 
bsr 
lea 
bsr 
moveq 


exit from wm_rptr without an error 

is non—zero which in turn means either that 
event (eg CTRL/F4) or that a loose item 

set a non—zero value in D4. If there was a 
no loose item) the appropriate bit will have 
Veo Weir tin ie SiN Aree. 


S @ Select key SG@lAll We) UNE TOR gin vem , 
be detected by WM_RPIR since the loose 

ine will have been called instead. The loose 
Tne can thienwesiot et hietevenitqu bit sine thiesse vient 
n exit from WM_RPIR by setting the event 
hat case the following code would be used. 
the loose item’s action routine could 
internally without exiting from WM _RPIR. 


(a4) ,al status area 
#p t__can , wsp_weve(al ) 
sul Exit 


#pt__move , wsp_weve(al ) 
wrpt 
move 
wrpt 


routines 


move 
wwl_item(a3),dl item number 
#wsi_mkav , ws_litem(al ,dl.w) ask for redraw 
#—1,d3 selective draw 
wm_lIdraw(a2) 

ws_litem(al ,dl.w) available 

#0 ,d4 

#0,d0 


#0 ,d0 
#pt__can ,d4 ESC 
#pt__can , wsp_weve(al ) 


(ae Wart 


al,—(sp) 

dwin 

cls clear window 
pt_l ,a5 text 

mtext 

#—1,d3 


141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
151 
152 
153 
154 
133 
156 
LS? 
158 
159 
160 
161 
162 
163 
164 
165 
166 
167 
168 
169 
170 
171 
Lee 
173 
174 
eo 
176 
LT? 
178 
179 
180 
181 
182 
183 
184 
185 
186 
187 
188 
189 
190 
19] 
192 
13 
194 
195 
196 
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moveq 
moveq 
bsr 
move.b 
subi. 1 
bmi 
cmpi.b 
bgt 
bsr 
beq 
bmi 
lea 
bra 
afl_er lea 
bra 
af1l_2 leva 
bra 
af1_3 lea 
af1l_4 bsr 
movea. 1 
bra 


; W— Where is the 


afun0_2 move.1 
bsr 

bsr 

lea 

bsr 
moveq 
moveq 
moveq 
bsr 
move.b 
subi. 1 
bmi 
cmpi.b 
bgt 

bsr 

beq 

bpl 

lea 

bra 
move. | 
movem. | 
lea 

lea 
movea.w 
jst 
movem. | 
lea 
moveq 
moveq 
bsr 
movea. 1 


af2_1 


#0 ,d7 
#io_fbyte ,d0 
tp3 

dl ,d7 
#°0’ ,d7 
afl_er 
#9 d7 
afl_er 
add_it 
au il 
af1_3 
te2 ,a5 
afl_4 
te6 ,a5 
afl_4 
te5 ,a5 
afl_4 
te4 ,a5 
mtext 
(sp)+,al 
afl 


item? 


al,—(sp) 
dwin 

cls 

pt_2 ,a5 
mtext 

#—1,d3 

#0 ,d7 
#io_fbyte ,d0 
tp3 

dl ,d7 

#°0’ ,d7 
afl_er 

#9 d7 
afl_er 
there 
af5_3 
af2_1 

tel ,a5 
afl_4 

dO ,num(aé6 ) 
a0/a2—3,—-(sp) 
num, al 

buf , a0 
cn_itohl ,a2 
(a2) 
(sp)+,a0/a2—3 
buf(a6),al 

#8 ,d2 
#io_sstrg ,d0O 
tp3 

(sp)+,al 


—_-—> 


_-—> 


_-—> 


_-—> 


item in D1.B 


0 to 9 (we hope) 
(te6) 


OK (te5 ) 
duplicate (te4) 
list full (te2) 


clear window 
text 


item in D1.B 


0 to 9 (we hope) 
(te6) 


Not There 
OK 


for printingn num(A6) 
keep regs 

arithmetic buffer 
space for answer 


replace regs 
for printing 
to print 8 bytes 


reset Al 


ey 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
222 
225 
224 
225 
226 
PER 
228 
220 
230 
oo8 
232 
233 
234 
235 
236 
237 
238 
20 
240 
241 
242 
243 
244 
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bra 


; H — How many in the 


afun0_4 move. 1 
bsr 
bsr 
bsr 
move .w 
movem. 


movea.w 


jst 
movem. 
movea. 
bra 


; D— Delete an 


afun0_5 move. 1 
bsr 
bsr 
lea 
bsr 
moveq 
moveq 
moveq 
bsr 
move.b 
subi. 1 
bmi 
cmpi.b 
bgt 
bsr 
bne 

af5_3 lea 
bra 

af5_1 era 
af5_2 bsr 


movea. 1 


bra 


hed1l 
hed1l 
hed1 
hed1l 


move. | 
moveq 

moveq 

jst 


dwin 


movea.1 


rts 


cls moveq 
moveq 
tp3 trap 


1 


1 
1 


item from the 


afl 
Nasste 


al, —(sp) 
dwin 

cls 
howmany 
d4,dl 

a2 —3,—(sp) 
ut_mint ,a2 
(a2) 
(sp)+,a2—3 
(sp)+,al 
afl 


Lhiesst 


all —(sp) 
dwin 

cls 

pt_5 ,a5 
mtext 
#—1,d3 
#0 ,d7 
#io_fbyte ,d0 
tp3 

dl ,d7 
#°0’ ,d7 
afl_er 
#9 ,d7 
afl_er 
drop_it 
af5_1 
te3 ,a5 
af5_2 
(@7 .25 
mtext 
(sp)+,al 
afl 


text 


> 


_-—> 


QUIN Sil 
<’W >,t2 
<’H’>,t3 
<’D’>,t4 


al, —(sp) 
#0,d1 

#7 ,d2 
wm_swinf (a2) 
(sp)+,al 


#—1,d3 
#sd_clear ,d0O 
#3 


return 


number —> A4 


clear window 


item in D1.B 


0 to 9 (we hope) 
(te6) 


OK 
>not there 


c) 


*>value dropped’ 
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rts 
; mtext prints the string @A5 
mtxt_reg reg dl —2/al—3 
mtext movem. | mtxt_reg ,—(sp) 
movea.w ut_mtext ,a2 
movea. 1 a5 ,al 
jst (a2) 
movem. | (sp)+,mtxt_reg 
rts 


; Adds item with value D7.L 


5 JB) = © 
ai_reg 
add_it 


ai5 


ai3 


ail 


ai4 
ai2 


it OC 2 
reg 
movem. | 
bsr 
cmpi.w 
ble 
move .w 
bra 


bsr 
ble 
moveq 
bra 
moveq 
bsr 
move. | 
Se oll 
bne 
move. | 
move. | 
ollie Il 
bra 
movea. | 
move. | 
move. 1 
move. | 
Conall 
move. | 
move. | 
moveq 
movem. | 
rts 


4p at mil 8 — iit Allmeaclhy wnere 


d0—1/d4/a0-1 

ai_reg ,—(sp) 

howmany 

#9 ,d4 

ai5 OK 
#1,d0 

ai2 Full 


there 

ai3 not already there 
#—1,d0 mark alredy there 
ai2 

#8 dl 

getsp 

d7 ,4( a0) Set item value 
fadd (a6) 

ail 

a0 , fadd (a6) 

a0, ladd(a6) 

(a0) 

ai4 

fadd(a6),al 

al ,( a0) 

(al) ,d0O 

a0 ,dl 

dl ,d0 

dO ,( al) update pointers 
a0 , fadd (a6) new start address 
#0 ,d0 mark OK 
(sp)+,ai_reg 


2 lomdelete the stem with value an DIE 


See Euresit 
2 (On xa 
di_reg 
drop_it 


famid’ > thie 
( JDO) .Ib, = 


reg 
movem. | 
bsr 
beq 
movea. 1] 


Hiei Nem Clelleie Wi 
0 NOT THERE 
1 Done OK 


d0—1/d4 —6/a0/a2/a4 
di_reg ,—(sp) 

there 

di6 not there 
dO ,a4 


309 
310 
ail 
312 
313 
314 
315 
316 
317 
318 
319 
320 
321 
322 
323 
324 
O25 
326 
S2T 
328 
B20) 
330 
331 
332 
a33 
334 
Bae 
336 
oot 
338 
339 
340 
341 
342 
343 
344 
345 
346 
347 
348 
349 
350 
351 
352 
333. 
354 
355 
356 
BOT 
358 
359 
360 
361 
362 
363 
364 
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item space to the heap 
is a previous address 
is a next address 


item to be deleted 1 


move. | (a4) ,dl 
Snr 4 ll d6,d1 next address 
; D6.L = previous address 
> A4.—E and DO.E = address to be deleted 
5 ID. = mex acldlress 
bsr rechp return 
ts tall! d6 
bne di3 there 
tst.l dl 
bne di4 there 
5 Mere tae Ibist as Cmlhy Une 
elr 1 fadd (a6) 
ellie gl ladd (a6 ) 
bra di8 
; next but no previous 


di4 move. | dl, fadd (a6) new Ist address 
movea. 1 dl ,a0 
di7 move. 1 a4 ,d0 
Or, Il dO ,( a0) 
di8 moveq #1,d0 mark OK 
di6 movem. | (sp)+,di_reg 
rts 
di3 ESiteol dl 
bne di5 both previous and 
4 next addresses 
; previous but no next 
move. | d6,ladd (a6) new last address 
movea. 1 d6 , a0 
bra di7 
; Both before (B) and after (A) the current (C) 
di5 movea.1] dl,a0 
move. | (a0) ,d3 AC 
movea.] d6,a0 
move. | (a0) ,d4 BC 
move. | (a4) ,d5 CC 
move. l a4 ,d0 C —> DO 
eor.1 dO ,d4 
eor.1 dl ,d4 New BC 
SO ll dO ,d3 
eor.1] d6 ,d3 New AC 
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366 movea.|1 dl1,a0 

367 move. | d3 ,( a0) set New AC 
368 

369 movea.|1 d6,a0 

370 move. 1 d4 ,( a0) set New BC 
371 

Sie bra di8 

373 

374 

375 

376 

377; Returns the number of items in the list in D4.W 
378; Uses no other registers 

379 | hm_reg reg dl —3/a0 

380 |) howmany movem. | hm_reg,—(sp) 

381 clr.w d4 

382 move. | fadd(a6),dl lst address 
383 beq hm1 none!!! 

384 Allie cll d2 

385 addq .w #1,d4 advance count 
386 |} hm2 movea. 1 dl ,a0 

387 move. | (a0) ,d3 pointer 

388 @ir , ll d2 ,d3 next address 
389 beq hm1 finished 

390 move. | dl ,d2 new previous 
391 move. | d3 ,dl new current 
392 addq .w #1,d4 advance count 
393 bra hm2 

394 | hm1 movem. | (sp)+,hm_reg 

395 tst.w d4 

396 rts number in D4.W 
397 

3987; There returns in DO.L the address of the item with value in D7 


399 Ee Di, Ee and ine Dor Ee the = previous address: 
4008; If not found DO.L = 0, 
401 2 1f ist empty DOeE = —1 


402; Uses no other registers 

403 

404 § th_reg reg d4/a0/a2 

405 § there movem. | th_reg ,—(sp) 

406 ollie all d6 previous address 
407 move. | fadd(a6),d0 lst address 
408 beq th4 List Empty 
409 bra thl 

410 § th2 movea.1 dO ,a2 

411 move. | d6 ,d4 

412 move. l dO ,d6 

413 move. | (a2) ,d0 pointer 

414 Corr. Il d4,d0 next address 
415 beq th3 not found 
416 § thl movea. 1 dO, a0 

417 cmp. | 4(a0),d7 found? 

418 bne th2 . . no 

419 § th3 movem. | (sp)+,th_reg 


420 PSE oll dod zero = not found: 


rts 


th4 moveq 
bra 


; program list 


pr_lIst dc. 
dc. 
dc. 
dec. 


<< € 


5 Siem Ist 


pt_lIst dc. 
dc. 
dc. 
dc. 


£2eés 


hed1 
hed1 
hed1 
hed1 


>; messages 


hed1 
hed1 
hed1 
hed1 
hed1 
hed1 
hed1 


in 


in 


lib 


in 


lib 


Thanks George. I appreciate your taking the time to go over some stuff I wrote many years ago, 


+ = found: 
— = empty 


#—1,d0 mark ’empty’ 
th3 


afunO_l—pr_Ist 
afunO_2—pr_Ist 
afun0_4—pr_Ist 
afunO_5—pr_Ist 


pt_l—pt_lIst 
pt_2—pt_lIst 
pt_4—pt_lIst 
pt_5—pt_lIst 


<’Give value to add ’>,pt_l 
<’Give value to find ’>,pt_2 
<’Size is °>,pt_4 

<’Give value to delete ’>,pt_5 


<’ List Empty’>,tel 
<’List Full’>,te2 
<’Not There’>,te3 

<’ Duplicate Item’>,te4 
<’ Value Added’>,te5 
<’Out of Range’>,te6 
<’ Value Dropped’>,te7 


winl_ass_pe_listw_asm 


winl_ass_pe_peas_sym_Ist 
winl_ass_pe_peas_bin 


winl_ass_pe_csprc_sym_lIst 


winl_ass_pe_csprce_bin 


Listing 7.5: George’s Linked List Example Program 


and bringing these “problems” to my attention. 


